Summary

This branch fixes several correctness bugs discovered across cache policies and concurrent stores, and adds regression tests to prevent recurrence.

Bug Fixes

• ConcurrentSlabStore TOCTOU race conditions — The old design used three separate RwLocks (for index, entries, and free list), creating time-of-check-to-time-of-use windows that could cause data corruption on concurrent update-after-remove, capacity overshoot under parallel inserts, and half-cleared state visible to readers during clear(). Refactored into a single SlabInner struct behind one RwLock to ensure atomicity across all mutations.

• ARC ghost-list directory leak — The Case 4 (complete miss) path was not properly pruning ghost lists B1/B2, violating the ARC paper's invariant that directory size (T1+T2+B1+B2) ≤ 2×capacity. Fixed to match the paper's eviction logic and added GhostList::evict_lru() to support it.

• Capacity-0 coercion in Clock, ClockPro, NRU — These policies silently coerced capacity=0 to capacity=1 via .max(1) in their constructors, inconsistent with the rest of the library. Now they honor capacity=0 and reject inserts gracefully.

• MFU insert return-value bug — MfuCore::insert at capacity=0 returned Some(value) (echoing the value back) instead of None. Fixed to return None for rejected inserts.

• MRU / SLRU / TwoQ CoreCache::insert inconsistency — The CoreCache trait impl duplicated update-in-place logic that diverged from each type's inherent insert method. Unified by having the trait impl delegate directly to the inherent method. The inherent insert now returns Option<V> (old value on update, None on fresh insert).

• ConcurrentWeightStore missing metrics — try_insert and remove delegated to the inner store without updating the external metrics counters for inserts, updates, and removes.

Enhancements

• ClockRing iterators — Added Iter, IterMut, IntoIter, Keys, Values, ValuesMut and IntoIterator impl for ClockRing.
• ClockRing documentation — Improved module docs with rustdoc intra-doc links and updated the operations table.

Tests Added

• tests/slab_concurrency.rs — Integration tests for TOCTOU update corruption, capacity overshoot, and atomic clear() under concurrency.
• tests/policy_invariants.rs — Cross-policy invariant tests for capacity-0 semantics (Clock, ClockPro, NRU).
• Per-policy unit regression tests for capacity-0 behavior, insert return values, and ARC ghost-list bounds.
• ConcurrentWeightStore metrics tracking tests for inserts, updates, removes, hits, and misses.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🧪 Test addition or modification

How Has This Been Tested?

• Unit tests
• Integration tests

Checklist

• My code follows the project's coding standards
• I have added tests for my changes
• All new and existing tests pass (cargo test)
• I have updated the documentation as needed